home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / cli / gulam.arc / GULAMDOC.ARC / more.doc < prev   
Internet Message Format  |  1988-10-20  |  8KB
  1. From myrias!mj Thu Oct 20 15:44:19 EDT 1988
  2. X-RN-Article: 12125 of comp.sys.atari.st
  3. >From: mj@myrias.UUCP (Michal Jaegermann)
  4. Newsgroups: comp.sys.atari.st
  5. Subject: Calling callgulam - explanation and example
  6. Keywords: gulam, shell
  7. Date: 19 Oct 88 23:47:47 GMT
  8. Organization: Myrias Research, Edmonton
  9.  
  10. (Whatever is described below was checked for a gulam version
  11. which identifies itself as:
  12.  
  13.     beta test version 1.03.04.05 121887 of
  14.     yet another shell for AtariST/TOS
  15.  
  16. Your mileage may vary!!)
  17.  
  18.    As you may not know, a very popular Gulam shell (many thanks to
  19. Prabhaker Mateti and Jwahar R. Bammi). includes quite powerful facility
  20. to invoke gulam services from a program started from gulam.  In contrast
  21. to many others shells floating aroung this is not done by executing
  22. the next incarnation of gulam. Instead there are provided two pointers
  23. which provide execution 'hooks' for all gulam commands.  A bright sight
  24. is that this approach does not take any extra memory and a start-up
  25. time is negligible. A dark side is that documentation describing this
  26. facility is either misleading or plainly wrong.  (As an aside - this
  27. is, alas, not the only place in documentation requiring touch-up.
  28. For this version, gulam.hlp, for example, does not correspond very well
  29. tp reality).
  30.  
  31.    This note is a kind of erratum, which, hopefuly, will help to clarify
  32. an ensuing confusion, which seems to be quite widespread.
  33.  
  34.    When you are running Gulam a TOS variable '_shell_p', at 0x4f6,
  35. contains an address of a location named 'togu_', which is the last entry
  36. in a 16 byte long table. The format of the table is (this is mostly quoted
  37. from the documentation):
  38.  
  39.                .long   0x86420135        / our magic number (4 bytes)
  40.                jmp     getlineviaue_     / 0x4ef9,address   (6 bytes)
  41.        togu_:  jmp     callgulam_        / 0x4ef9,address   (6 bytes)
  42.  
  43. It clearly follows from that that magic number is located 10 bytes before
  44. 'togu_' and not, the documentation suggested, 12.  What's more, the magic 
  45. number should be equal *(long *)(*(char **)0x4f6 - 10), instead of a
  46. given *((long *)0x46fL - 12L), which will produce a value from an address
  47. way off.  On the top of it, an actual magic number in my copy of Gulam
  48. is not like the documented but it equals 0x00420135.  Use Gulam 'peekw'
  49. to check what you got. To be on a safe side, until the matter
  50. is fully clarified, I am using only a lower half of the magic number,
  51. which seems to be correct; i.e. short_magic = *(short *)(*(char **)0x4f6-8).
  52.  
  53.   Two other items in the table are entry points to two functions
  54. 'getlineviaue' and 'callgulam'.  The information given in the documentation
  55. about them is mostly correct, with a similar mix-up in a calculation
  56. of an address of entry to 'getlineviaue', like the one described above.
  57. Also, strictly speaking, 'getlinevalue' does not return anything, since
  58. it is declared as 'void'. As a side effect it modifies a contents of
  59. a user supplied buffer, copying there a contents of a command line. It
  60. would be probably more convenient if, instead of being void, it would return
  61. something useful, say a number of copied characters, but it doesn't,
  62. so we may have to live with that.  Just to make our life more
  63. interesting, the other function, 'callgulam', returns 'int' - the return
  64. status of an executed command.  This makes wonders to types of your
  65. pointers.  See the supplied program example for to see how to cast.
  66. All of this to ensure that your C-compiler will not get totally lost.
  67. If you have a compiler which accepts the stuff in a form from an original
  68. docs - replace your compiler. Fast!
  69. (As an aside - all this pointer play would be easier in assembler, 
  70. if you feel so inclined).
  71.  
  72.   While experimenting whith the program example try the following.
  73. Call 'ue' on some file, position cursor somewher down the text and
  74. stop editor with ^Z. Try some other commands and upon return to Gulam
  75. type 'fg'.  Repeat experiment stopping the editor in Gulam and typing
  76. 'fg' from the demo program prompt. Don't you think that this is a nice
  77. way to run editor for your, say, Lisp interpreter?
  78.  
  79.   Some things are still missing. One cannot tell 'ue', on a command
  80. line, to load a file and go to the line 247.  Or there is a way and I
  81. am simply not aware of it?  And I know of no way to grab a result of
  82. a command, stuff it into a variable and use it for a test of conditional
  83. script execution.  Oh well, maybe in some future release...
  84.  
  85.   Two other, non-interactive, ways of calling Gulam are also mentioned
  86. in docs.  I did not try 'Pexec method', but attempts to execute 
  87. gulam as a program with arguments, as described, produced only
  88. nonsensical error messages about 'invalid regexp' and error number -33.
  89. Can anybody shed some light on that matter?
  90.  
  91.  
  92.    Michal Jaegermann
  93.    Myrias Research Corporation
  94.    Edmonton, Alberta, CANADA
  95.    ...alberta!myrias!mj
  96.    (or you may try mj@myrias.UUCP)
  97.  
  98. ------------------------------------------------------------------------------
  99.  
  100. /* 
  101. * A demo program to show a usage of Gulam 'hooks' - call from
  102. * Gulam shell!  When asked, try different gulam commands, ue
  103. * in particular.
  104. *
  105. * A numbers of pointers floating around is a little bit higher
  106. * than necessary, but we will waiste some memore for the sake
  107. * of clarity.
  108. *
  109. * Michal Jaegermann, October 1988
  110. */
  111.  
  112. #include <stdio.h>
  113. #include <osbind.h>
  114. #include <string.h>
  115. #define  SHELLP         ((char **) 0x04f6L)
  116. #define  G_MAGIC        0x0135
  117.  
  118. main()
  119. {
  120.        long save_ssp;
  121.        short sh_magic;
  122.        char buf[258];
  123.        char *tgptr;            /* storage for togu_         */
  124.        /* if you really would like to have it right, then   */
  125.        /* tgptr should be a pointer to void -             */
  126.        /* a bit of overkill on ST :-)                */
  127.        
  128.                       
  129.        int  (* cgp)();         /* pointer to callgulam()    */
  130.                                /* also contains togu_, but  */
  131.                                /* a type is different       */
  132.        void (* glp)();         /* pointer to getlineviaue() */
  133.  
  134.        fprintf(stderr, "Welcome to callgulam demo.\n");
  135.        save_ssp = Super(0L);
  136.        tgptr = *SHELLP;
  137.        Super(save_ssp);
  138.  
  139.        if (G_MAGIC != (sh_magic = *((short *)(tgptr - 8)))) {
  140.                fprintf (stderr, "wrong magic value %x\n", sh_magic);
  141.                exit (1);
  142.        }
  143.  
  144.        cgp = *((int (*)()) tgptr);
  145.        glp = *((void (*)()) (tgptr - 6));
  146.        (* cgp)("echo 'test of Gulam'");
  147.        (* cgp)("echo 'executing ls -l'");
  148.        (* cgp)("ls -l");
  149.        (* cgp)("echo '-----------------'");
  150.        (* cgp)("ls -R -t a:\\ ");
  151.        (* cgp)("echo ' '");
  152.        (* cgp)("echo ' '");
  153.        (* cgp)("set tmp_old_prompt $prompt");
  154.        (* cgp)("set prompt 'At your service, Sir!'");
  155.                /* change a gender if a need will arise */
  156.        (* cgp)("echo 'Awaiting your commands!!'");
  157.        /* the following loop will cycle until it will get an empty line */
  158.        while ((* glp)(buf), putchar('\n'), 0 != strlen(buf)) {
  159.                                        /* the new line not supplied */
  160.                                        /* by Gulam - DIY, mate       */
  161.                (* cgp)(buf);
  162.        }
  163.        (* cgp)("set prompt $tmp_old_prompt");
  164.        (* cgp)("unset tmp_old_prompt");
  165.        fprintf (stderr,"\nNice talking to you, see you later.\n");
  166.        exit(0);
  167. }
  168. /* -----------------/ that is all for today /--------------------- */
  169.  
  170. -- 
  171.     Michal Jaegermann
  172.     Myrias Research Corporation
  173.     Edmonton, Alberta, CANADA
  174.     ...{ihnp4, ubc-vision}!elberta!myrias!mj
  175.  
  176.